<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 8.5</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="8.4.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="9.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P1">Part I. The Language</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#8">Chapter 8. Compilation, Execution, and Errors</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><a name="xpcall"><h2>8.5 &ndash; Error Messages and Tracebacks</h2></a>

<p>Although you can use a value of any type as an error message,
usually error messages are strings describing what went wrong.
When there is an internal error
(such as an attempt to index a non-table value),
Lua generates the error message;
otherwise, the error message is the value passed to
the <code>error</code> function.
In any case,
Lua tries to add some information about the location
where the error happened:
<pre>
    local status, err = pcall(function () a = 'a'+1 end)
    print(err)
     --> stdin:1: attempt to perform arithmetic on a string value
    
    local status, err = pcall(function () error("my error") end)
    print(err)
     --> stdin:1: my error
</pre>
The location information gives the file name
(<code>stdin</code>, in the example)
plus the line number (1, in the example).

<p>The <code>error</code> function has an additional second parameter,
which gives the <em>level</em> where it should report the error;
with it, you can blame someone else for the error.
For instance, suppose you write a function
and its first task is to check whether it was called correctly:
<pre>
    function foo (str)
      if type(str) ~= "string" then
        error("string expected")
      end
      ...
    end
</pre>
Then, someone calls your function with a wrong argument:
<pre>
    foo({x=1})
</pre>
Lua points its finger to your function---after all,
it was <code>foo</code> that called <code>error</code>---and not to the real culprit,
the caller.
To correct that, you inform <code>error</code> that the error you
are reporting occurred on level 2 in the calling hierarchy
(level 1 is your own function):
<pre>
    function foo (str)
      if type(str) ~= "string" then
        error("string expected", 2)
      end
      ...
    end
</pre>

<p>Frequently, when an error happens,
we want more debug information than only the
location where the error occurred.
At least, we want a traceback,
showing the complete stack of calls leading to the error.
When <code>pcall</code> returns its error message,
it destroys part of the stack
(the part that went from it to the error point).
Consequently, if we want a traceback,
we must build it before <code>pcall</code> returns.
To do that, Lua provides the <code>xpcall</code> function.
Besides the function to be called,
it receives a second argument, an <em>error handler function</em>.
In case of errors,
Lua calls that error handler <em>before the stack unwinds</em>,
so that it can use the debug library to gather any extra
information it wants about the error.
Two common error handlers are <code>debug.debug</code>,
which gives you a Lua prompt so that you can inspect by
yourself what was going on when the error happened
(later we will see more about that, when we discuss the debug library);
and <code>debug.traceback</code>,
which builds an extended error message with a traceback.
The latter is the function that the
stand-alone interpreter uses to build its error messages.
You also can call <code>debug.traceback</code> at any moment to get a
traceback of the current execution:
<pre>
    print(debug.traceback())
</pre>

<p>
<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="9.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

